---
title: OSS-Compass 平台前端开发指南（一）：技术栈和开发环境详解
tags:
  - 博客
authors:
  - name: 赖兴友
    title: OSS-Compass 社区软件开发工程师
---

在开源社区蓬勃发展的浪潮中，OSS-Compass 构建了基于指标模型的开源项目评估体系，历经两年的打磨与沉淀，其功能不断完善，社区日益壮大。对于有志于在 OSS-Compass 社区发光发热的开源开发者而言，深入理解项目前端技术架构是开启贡献大门的关键钥匙之一。

在本文中，我们将深入探讨 OSS-Compass 平台的[前端主仓](https://github.com/oss-compass/compass-web)的项目架构和开发环境，涵盖其技术栈、文件结构、路由系统、API 交互、开发环境搭建等关键部分，帮助读者理解其背后的设计思路和实现细节。而在后续的系列文章中，我们还将深挖项目分类仓管理技巧，探索文档仓构建与优化方法，钻研 API 交互细节以提升数据交互效能。期望借这一系列内容，为开发者们提供实操经验，助力大家在 OSS - Compass 社区稳步踏出贡献步伐 。

<!--truncate-->

### 1. 架构模式

OSS-Compass 前端采用了基于 React 的单页应用（SPA）架构模式，结合 Next.js 实现了服务端渲染（SSR）。选择 React 作为构建用户界面的基础，是因其虚拟 DOM 机制能高效地处理界面更新，以组件化开发模式将复杂页面拆分成一个个独立、可复用的模块，极大提升了代码的维护性与可扩展性。在 OSS-Compass 里，无论是基础的按钮、搜索框组件，还是像分析页模型数据图表这类复杂页面组件，都被精心封装，每个组件专注自身功能逻辑，降低了代码耦合度。而 Next.js 的引入为项目带来 SSR 与 SSG 特性，这有助于提高页面性能并改善搜索引擎优化（SEO），并极大提升了用户操作响应速度与体验。

### 2. 核心技术栈

| **技术分类**                                             | **技术选型**              | **选型理由与关键实践**                                                                             |
| -------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
| ** 核心框架 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;** | React + TS + Next.js      | 基于组件化开发模式，通过 TS 实现接口类型约束，Next.js 实现 SSR。                                   |
| **样式方案**                                             | Tailwind CSS              | 实用优先的 CSS 框架，用于快速构建样式。                                                            |
| **组件库**                                               | Ant Design                | 开源 UI 设计语言和组件库，不仅具有美观的设计，而且经过了大量的实践验证，具有良好的稳定性和易用性。 |
| **可视化**                                               | ECharts                   | 广受好评的图表可视化开源框架，社区在 OSS-Compass 平台度量评分高，优于其他竞品 。                   |
| **状态管理**                                             | Context API               | 在组件之间共享状态的简单而轻量的方法。                                                             |
| **工程化**                                               | ESLint + Prettier + Husky | 用于识别和报告 JavaScript 代码中的问题，提交前自动格式化。                                         |
| **国际化**                                               | i18next                   | 多语言文件按命名空间拆分（如：`i18n/{lang}/common.json`），支持 SSR 动态加载。                     |

### 3. 文件结构

```plaintext
web/src/
├── common/          // 可复用组件、常用工具函数、公用hooks
├── pages/           // 文件系统路由
├── modules/         // 路由对应的模块化页面、如分析页、Lab页、协作页等
└── styles/          // 样式文件（Tailwind 和自定义样式）

web/i18n/
└── {lang}           // 国际化配置

graphql/
└── src/gql/         // Graphql API 请求
```

### 4. 路由系统

Next.js 使用文件系统作为路由的基础，每个在 pages 文件夹中的文件都会自动对应一个路由。这种方式使得路由的管理变得简单且直观。例如：

```plaintext
pages/
├── analyze/            // 模型分析页面路由
│      └──[slugs].tsx   // 模型分析页动态路由 slugs 为项目id
├── collaboration/      // 协作页路由
└── lab/                // Lab页路由
```

Next.js 支持动态路由，使得开发者可以根据 URL 参数动态渲染页面。通过使用方括号（[]）语法，可以轻松实现动态路由。例如，[slugs].tsx 文件可以用于展示项目的模型评估信息。

### 5. API 交互

OSS-Compass 采用 GraphQL 进行前后端数据交互 。与传统的 RESTful API 相比，GraphQL 允许前端精确地指定需要获取的数据，后端只会返回前端请求的数据，避免了数据的过度获取或不足获取。例如，在获取用户的登录信息时，前端可以通过 GraphQL 查询只请求用户的名称、头像等必要字段，而无需像 RESTful API 那样可能获取到大量不需要的额外数据。这样不仅减少了数据传输量，提高了应用性能，还使得数据请求更加灵活和可定制。

### 6. 开发流程与规范

**(1) 开发环境搭建**

- 安装依赖：首先，需要克隆 OSS-Compass 的前端项目仓库到本地。进入项目目录后，使用 yarn 安装项目所需的依赖包。项目的 package.json 文件中已经列出了所有依赖，包括 React、Next.js、Tailwind CSS 等相关库。​
- 配置环境变量：配置后端 API 的地址环境变量，在项目 web 目录下.env.local 文件，并在其中添加后端 API 的地址来进行配置。​
- 启动开发服务器：安装完依赖并配置好环境变量后，使用 yarn dev 命令启动开发服务器。此时，浏览器会自动打开项目的本地开发地址，开发者可以在浏览器中实时预览和调试代码。

**(2) 代码规范 ESLint 、Prettier、Husky **

OSS-Compass 项目使用 ESLint 进行代码质量检查，使用 Prettier 进行代码格式化，使用 Husky 在提交前执行 ESLint 脚本。ESLint 能够检测代码中的语法错误、潜在的逻辑问题以及不符合代码规范的地方，而 Prettier 则可以自动格式化代码，使其风格统一，相关配置文件可在 web 根目录中查看。在开发过程中，建议开发者在编辑器中安装 ESLint 和 Prettier 插件，这样在保存文件时，编辑器会自动根据配置对代码进行检查和格式化。

### 7. 总结

通过深入了解 OSS-Compass 前端技术栈，掌握开发流程，开发者可前往 [OSS-Compass 社区仓库](https://github.com/oss-compass) 查看源码、issues，参与社区讨论，寻找自己感兴趣且有能力解决的问题并尝试贡献代码。 希望本文能够成为你开启 OSS-Compass 开源贡献之旅的指南，让我们共同努力，推动 OSS-Compass 在开源评估领域不断前行，为全球用户带来更优质的服务。
